Alemba API Programmers' Cookbook

This section of the documentation contains information on how to use the API to create well-formed Alemba objects, i.e. objects in the vFire database that contain the data and relationships necessary for those objects to behave in a manner that is compatible with objects created by the suite of vFire applications.

The role of the Alemba rules engine

The business logic that determines how objects behave after creation is contained in the Alemba rules engine (also known as Infra Rules). Some examples of what it does are:

• The initial routing of calls
• The creation and progression of tasks for new requests
• The application of SLAs and other agreements
• Creating history entries

This engine is invoked when objects are created via the API, so the rules therein will be automatically applied, just as they are for objects created via vFire interfaces. This simplifies using the API in a large number of cases – all the API user has to do is to set the values that will trigger those rules and the engine will take care of the rest. The key properties and parameters that impact behaviour are covered in the recipes.

Processes that don’t use the rules engine

There are some processes which must operate across multiple transactions and require user interaction. In these cases, the API user has more work to do – to create things in the right order, and to link the objects correctly. One such example is the creation of Service Orders - details for how to do this are given in Creating a Service Order.

Implications of the difference between a WCF and RESTful API

In the Classic WCF (Windows Communication Foundation) API, some transactions include parameters that not only impact the main subject of the transaction, but also create, link or update other related objects. This kind of hybrid action is not appropriate in an API whose nature is to enable state transfers, rather than to implement compound rules-driven behaviour. The same ends can be achieved in other ways, and these are described in the cookbook.

Cooking principles - Lock before you update

The following example refers to Call, but applies to all lockable items, such as Assets and Tickets (Calls, Requests and Tasks) and their sub-types.

Before performing an update in vFire Core, you need to Take Action in Core, which as well as assigning the call to yourself. The Core user interface also locks the call, until you close the call screen. You need to follow equivalent principles when using the API to ensure consistent operation with the Core application

Note that in the API, the actions available to you will depend on the state of the record, and the subset of actions that you should attempt are subject to your privileges.

When you Get a record:

If it is not locked	the only PUT/POST action described will be Lock
If it is locked by someone else	the lock action may fail. The response will tell you who has locked that record "Message": "Record locked by Jessica Mercato", "SubStatus": "None", "Type": "HttpStatusException" }
If it is already locked by you	all PUT/POST actions that are appropriate to the record in its current state will be described including Unlock (but not Lock)

 

Other actions may work, even if they are not listed for the current state of the entity. But there is a higher likelihood that they will fail.

When you Lock a record:

If the lock does not succeed – (because someone else has locked it in the meantime and you do not have the Take Over Calls privilege)	Retry a limited number of times, and if still failing, either report an error or try again later, according to the nature of the activity If you succeed during a retry, Get the record again and check its timestamp (LastActionDate). If changed, validate that it is still in a state where it makes sense to apply your changes, and proceed if so
If the lock succeeds	all PUT/POST appropriate actions will be available.

 

Now you can perform the desired action.

If the action fails (because someone else has locked it in the meantime)

Note how many times the action has failed and limit action retries to avoid endlessly looping. Go back to trying to lock the record as above.

If the action succeeds

If you need to perform further actions on the same record, proceed with those actions. Some actions – e.g. Defer, Forward, Close – automatically perform an Unlock too. If you need to perform further actions after this, you may need to lock the object again. The response to any action, also includes a list of suggested actions applicable to the current state. If you have finished with the record, you must ensure that it is unlocked – the API will not do this automatically until the current session expires, although unlocking is implied by some ticket actions (Defer, Forward, Close). Locked records will eventually be unlocked when the current session expires, just as in vFire Core. This follows the same pattern as implemented across the vFire product set, and should not cause unexpected behavior in those products.